Module VoiceCommand

Class RecoProp

RecoProp.value
RecoProp.children Table in the propName=RecoProp format

Class RecoResult

RecoResult.phrase The phrase that was spoken
RecoResult.confidence Recognition engine confidence
RecoResult.props The properties and their values that were defined when constructing the Phrase.
RecoResult:getProp(...) Convenience method for retrieving property values.

Class Phrase

.

Class PhraseBuilder

PhraseBuilder.new() Constructor
PhraseBuilder:append(element[, propName]) Appends an element
PhraseBuilder:append(args) Appends an element.
PhraseBuilder:append(choices[, propName]) Appends a multiple-choice element.
PhraseBuilder:appendOptional(element[, propName]) Appends an optional element.
PhraseBuilder:appendOptional(choices[, propName]) Appends an optional multiple-choice element.
PhraseBuilder:build([asString]) Builds the phrase

Class VoiceCommand

VoiceCommand:new() Constructor
VoiceCommand:new(phrase[, confidence=0.93]) Constructor
VoiceCommand:new(args) Constructor
VoiceCommand.resetGrammar() Call this function inside a plugin lua before activating or deactivating voice commands.
VoiceCommand:getPhrases(dummy) Returns all phrase variants of a voice command.
VoiceCommand:setPersistence(persistenceMode) Sets persistence mode of a voice command.
VoiceCommand:addPhrase(phrase, dummy) Adds phrase variants to a voice command.
VoiceCommand:removeAllPhrases(dummy) Removes all phrase variants from a voice command.
VoiceCommand:setConfidence(confidence) Sets required confidence of a voice command.
VoiceCommand:activate()
VoiceCommand:ignore()
VoiceCommand:deactivate()
VoiceCommand:disable() Deactivates the voice command and makes successive calls to activate and ignore have no effect.
VoiceCommand:getAction() If the voice command has only one action, returns that action.
VoiceCommand:activateOn(...) The voice command will become active when the events passed as parameters are triggered.
VoiceCommand:deactivateOn(...) The voice command will be deactivated when the events passed as parameters are triggered.
VoiceCommand:ignoreOn(...) The voice command will go into ignore mode when the events passed as parameters

are triggered.
VoiceCommand:removeEventRef(refType, ...) Disables the effect of activateOn, deactivateOn or ignore for the default voice commands in copilot.voiceCommands


Class RecoProp

RecoProp.value
RecoProp.children
Table in the propName=RecoProp format

Class RecoResult

The payload of a VoiceCommand event

Usage:

local helloGoodbye = VoiceCommand:new {
  phrase = PhraseBuilder.new()
    :append {
      propName = "what",
      choices = {
        {
          propVal = "greeting",
          choice = PhraseBuilder.new()
            :append "hello"
            :appendOptional({"there", "again"}, "optProp")
            :build()
        },
        "goodbye"
      },
    }
    :appendOptional "friend"
    :build(),
  persistent = true,
  action = function(_, recoResult)
    print(recoResult:getProp("what")) -- "greeting" or "goodbye"
    print(recoResult:getProp("what", "optProp"))  -- "there", "again" or nil
  end
}

copilot.callOnce(function()
  helloGoodbye:activate()
end)
RecoResult.phrase
The phrase that was spoken
RecoResult.confidence
Recognition engine confidence
  • confidence number
RecoResult.props
The properties and their values that were defined when constructing the Phrase. If a property-bound phrase element is optional and the element is absent in the spoken phrase, props.propName will be nil.
  • props table Table in the propName=RecoProp format.
RecoResult:getProp(...)
Convenience method for retrieving property values.

Parameters:

  • ... path Strings denoting the tree path to the wanted property. If the first argument is a RecoProp, the search will be started there.

Returns:

  1. string The value field of the RecoProp
  2. RecoProp

Or

  1. nil
  2. nil

Class Phrase

Allows you to create complex phrases containing multiple-choice and optional elements that can be bound to named properties.

A Phrase can be used on its own and as a building block for composing other Phrases. A Phrase can have multiple parent Phrases as well as multiple child Phrases.

Use the PhraseBuilder class to create a Phrase (which itself is immutable).

.
  • .

Class PhraseBuilder

Builds a Phrase
PhraseBuilder.new()
Constructor
PhraseBuilder:append(element[, propName])
Appends an element

Parameters:

  • element A string or Phrase
  • propName string Name of the property (optional)

Returns:

    self
PhraseBuilder:append(args)
Appends an element.

Parameters:

  • args
    • propName string Name of the property
    • optional bool Whether this element is optional (default false)
    • asString string Alias for the elements's string representation in the logs. (optional)
    • choices Either a single string or Phrase or an array of choices where a choice can be:
      • A table with a propVal and a choice field that is either a string or Phrase
      • A string or a Phrase

Returns:

    self

Usage:

    PhraseBuilder.new():append {
   propName = "what",
   choices = {
     "goodbye", -- same as {propVal = "goodbye", choice = "goodbye"}
     {propVal = "greeting", choice = "hi"},
     {
       propVal = "greeting",
       choice = PhraseBuilder.new()
         :append "good day"
         :appendOptional("sir", "extraPolite")
         :build()
     },
     {propVal = "greeting", choice = "hello"}
   },
 }:build()
PhraseBuilder:append(choices[, propName])
Appends a multiple-choice element.

Parameters:

  • choices table An array of choices where a choice can be:
    • A table with a propVal and a choice field that is either a string or Phrase
    • A string or a Phrase
    If you have Phrases in the list, consider using the above overload for readability
  • propName string Property name. (optional)

Returns:

    self

Usage:

    PhraseBuilder.new():append({"hello", "goodbye"}, "what"):build()
PhraseBuilder:appendOptional(element[, propName])
Appends an optional element.

Parameters:

  • element A string or a Phrase
  • propName string Property name. (optional)

Returns:

    self
PhraseBuilder:appendOptional(choices[, propName])
Appends an optional multiple-choice element.

Parameters:

  • choices See above
  • propName string Property name. (optional)

Returns:

    self
PhraseBuilder:build([asString])
Builds the phrase

Parameters:

  • asString string Alias for the phrase's string representation in the logs. (optional)

Returns:

    A Phrase object

Class VoiceCommand

VoiceCommand is a subclass of Event and is implemented with the Windows Speech API.

A voice command can be in one of these states:

  • Active

  • Inactive

  • Ignore mode: the phrases are active in the recognizer but recognition events don't trigger the voice command.

If you only have a couple of phrases active in the recognizer at a given time, especially short ones, the accuracy will be low and the recognizer will recognize just about anything as those phrases. On the other hand, having a lot of active phrases will also degrade the quality of recognition.

A VoiceCommand event emits a RecoResult as its payload.

VoiceCommand:new()
Constructor
VoiceCommand:new(phrase[, confidence=0.93])
Constructor

Parameters:

  • phrase A string or Phrase or array of strings and Phrase objects
  • confidence number Required recognition engine confidence between 0 and 1 (default 0.93)
VoiceCommand:new(args)
Constructor

Parameters:

  • args A table containing the following fields (also the fields taken by the parent constructor):
    • phrase string or Phrase or array of strings and Phrase objects.
    • dummy string or Phrase or array of strings and Phrase objects. One or multiple dummy phrase variants which will activated and deactivated synchronously with the voice command's actual phrase variants to help the recognizer discriminate between them and similarly sounding phrases.
    • confidence number Required recognition engine confidence between 0 and 1 (default 0.93)
    • persistent
      • omitted or false: the voice command will be deactivated after being triggered.
      • 'ignore': the voice command will be put into ignore mode after being triggered.
      • true: the voice command will stay active after being triggered.
      (default false)

Usage:

    local myVoiceCommand = VoiceCommand:new {
 phrase = "hello",
 confidence = 0.95,
 action = function(_, recoResult) print "hi there" end
}
VoiceCommand.resetGrammar()
Call this function inside a plugin lua before activating or deactivating voice commands.
You also need to call this after modifying the existing phrase set in any way for the changes to take place.
VoiceCommand:getPhrases(dummy)
Returns all phrase variants of a voice command.

Parameters:

  • dummy bool True to return dummy phrase variants, omitted or false to return actual phrase variants.

Returns:

    Array of Phrase objects
VoiceCommand:setPersistence(persistenceMode)
Sets persistence mode of a voice command.

Parameters:

  • persistenceMode
    • omitted or false: the voice command will be deactivated after being triggered.
    • 'ignore': the voice command will be put into ignore mode after being triggered.
    • true: the voice command will stay active after being triggered.

Returns:

    self
VoiceCommand:addPhrase(phrase, dummy)
Adds phrase variants to a voice command.

Parameters:

  • phrase string or array of strings
  • dummy bool True to add dummy phrase variants, omitted or false to add actual phrase variants.

Returns:

    self
VoiceCommand:removeAllPhrases(dummy)
Removes all phrase variants from a voice command.

Parameters:

  • dummy bool True to remove dummy phrase variants, omitted or false to remove actual phrase variants.

Returns:

    self
VoiceCommand:setConfidence(confidence)
Sets required confidence of a voice command.

Parameters:

  • confidence number A number from 0-1

Returns:

    self
VoiceCommand:activate()

Returns:

    self
VoiceCommand:ignore()

Returns:

    self
VoiceCommand:deactivate()

Returns:

    self
VoiceCommand:disable()
Deactivates the voice command and makes successive calls to activate and ignore have no effect.
VoiceCommand:getAction()
If the voice command has only one action, returns that action. All default voice commands have only one action.
VoiceCommand:activateOn(...)
The voice command will become active when the events passed as parameters are triggered.

Adds an 'activate' event reference that can be removed from the event via removeEventRef

Parameters:

  • ... one or more events
VoiceCommand:deactivateOn(...)
The voice command will be deactivated when the events passed as parameters are triggered.

Adds a 'deactivate' event reference that can be removed from the event via removeEventRef

Parameters:

  • ... one or more events
VoiceCommand:ignoreOn(...)
The voice command will go into ignore mode when the events passed as parameters

are triggered.

Adds a 'ignore' event reference that can be removed from the event via removeEventRef

Parameters:

  • ... one or more events
VoiceCommand:removeEventRef(refType, ...)
Disables the effect of activateOn, deactivateOn or ignore for the default voice commands in copilot.voiceCommands

Parameters:

  • refType string 'activate', 'deactivate' or 'ignore'
  • ... one or more Event's

Usage:

    copilot.voiceCommands.gearUp:removeEventRef('activate',
copilot.events.goAround, copilot.events.takeoffInitiated)
generated by LDoc 1.4.6 Last updated 2021-11-11 17:10:49